feat(cli): add allowHeadless option for MCP servers in headless mode #9327

aaronlippold · 2025-12-26T15:24:45Z

Description

Adds allowHeadless: true config option for MCP servers, enabling specific MCP tools to work in headless mode without requiring the --auto flag.

Problem: MCP tools are unavailable in headless mode, limiting automation scenarios where users want specific trusted MCP servers to work while still requiring approval for other tools.

Solution: Per-server allowHeadless option that allows enumeration and execution of tools from that server in headless mode.

Usage:

mcpServers:
  - name: Brave Search
    command: npx
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    allowHeadless: true  # Enable in headless mode

Changes

Commit 1: Feature (`4062ff6`)

Add allowHeadless to MCP config schema (packages/config-yaml)
Pass allowHeadless from connection config to Tool objects
Check allowHeadless in tool enumeration (getRequestTools)
Check allowHeadless in execution permission (checkToolPermissionApproval)
Security: allowHeadless respects explicit "exclude" permissions (won't override user denials)
Add 9 unit tests in mcp-headless.test.ts

Commit 2: Test Isolation Fix (`4db8aa8`)

Mock core/util/paths.js to read CONTINUE_GLOBAL_DIR dynamically
Fixes test isolation issue where GlobalContext singleton would leak state between parallel test files
Add interopDefault: true to vitest config for better CommonJS handling

AI Code Review

Team members only: AI review runs automatically when PR is opened or marked ready for review
Team members can also trigger a review by commenting @continue-review

Checklist

I've read the contributing guide
The relevant docs, if any, have been updated or created
The relevant tests, if any, have been updated or created

Screen recording or screenshot

N/A - This is a CLI/config change with no UI impact.

Tests

Added 9 unit tests in extensions/cli/src/stream/mcp-headless.test.ts:

Tool enumeration tests (4):

Exclude MCP tools by default in headless mode
Include MCP tools when allowHeadless=true in headless mode
Include all MCP tools in interactive mode regardless of allowHeadless
Handle multiple MCP servers with different allowHeadless settings

Execution permission tests (5):

Approve MCP tool with allowHeadless=true in headless mode
Deny MCP tool without allowHeadless in headless mode
Deny MCP tool with allowHeadless=undefined in headless mode
Approve explicitly allowed tools regardless of allowHeadless
Deny explicitly excluded tools even with allowHeadless=true (security test)

All existing tests continue to pass (1715 unit tests, 66 e2e tests).

continue · 2025-12-26T15:24:48Z

Learn more

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

Unsubscribe from All Green comments

continue-development-app · 2025-12-26T15:24:48Z

Learn more

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

Unsubscribe from All Green comments

cubic-dev-ai

2 issues found across 7 files

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="extensions/cli/src/stream/mcp-headless.test.ts">

<violation number="1" location="extensions/cli/src/stream/mcp-headless.test.ts:238">
P2: Test claims to test `allowHeadless=undefined` but actually tests `allowHeadless=false` due to `?? false` coercion in the helper. To properly test undefined behavior, preserve the undefined value instead of defaulting to false.</violation>
</file>

<file name="extensions/cli/src/stream/handleToolCalls.ts">

<violation number="1" location="extensions/cli/src/stream/handleToolCalls.ts:206">
P1: The `allowMcpInHeadless` check doesn&#39;t respect explicit `&quot;exclude&quot;` permissions. If a tool is explicitly excluded in permissions but has `allowHeadless: true`, it will bypass the exclusion and be allowed in headless mode. The `allowHeadless` flag should only upgrade `&quot;ask&quot;` permissions to automatic approval, not override explicit exclusions.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Tag @cubic-dev-ai to re-run a review.}

extensions/cli/src/stream/mcp-headless.test.ts

extensions/cli/src/stream/handleToolCalls.ts

continue · 2025-12-26T15:29:16Z

📚 Documentation Updates Available

I've created documentation updates for this feature in a separate branch: docs/mcp-allow-headless-9327

Changes Overview

Reference Documentation (reference.mdx)

Added allowHeadless property to mcpServers configuration section
Added example showing usage with Brave Search MCP server

MCP Deep Dive (customize/deep-dives/mcp.mdx)

Added comprehensive section "How to Use MCP Servers in CLI Headless Mode"
Explained security rationale with Note and Warning components
Provided usage examples and best practices
Added CardGroup showing good candidates vs. cautionary use cases

CLI Overview (cli/overview.mdx)

Updated tool permissions Info box to mention MCP tools headless behavior
Linked to detailed documentation

Next Steps

You can:

Review the changes in my branch: docs/mcp-allow-headless-9327
Cherry-pick the documentation commit (8aff77c) into your PR branch
Or I can create a separate PR to main after this PR merges

The documentation changes are scoped to explain the feature without adding unnecessary detail, using Mintlify components for effective information display.

View the commit: 8aff77c

continue · 2025-12-26T15:29:40Z

📚 Documentation PR Created

I've created PR #9328 with documentation updates for the allowHeadless feature.

The PR adds comprehensive documentation covering:

✅ Reference documentation for the allowHeadless property
✅ Detailed explanation in the MCP deep dive guide
✅ Updated CLI overview to mention MCP headless behavior
✅ Security considerations and best practices
✅ Usage examples with Mintlify components

The documentation PR is ready to merge once this PR is merged.

Preview: #9328

Adds `allowHeadless: true` config option for MCP servers, enabling specific MCP tools to work in headless mode without requiring --auto flag. Changes: - Add allowHeadless to MCP config schema - Pass allowHeadless from connection config to Tool objects - Check allowHeadless in tool enumeration (getRequestTools) - Check allowHeadless in execution permission (checkToolPermissionApproval) - Respect explicit "exclude" permissions (allowHeadless cannot override) - Add 9 tests covering enumeration, execution, and security scenarios Usage: ```yaml mcpServers: - name: Brave Search command: npx args: ["-y", "@modelcontextprotocol/server-brave-search"] allowHeadless: true # Enable in headless mode ``` Authored by: Aaron Lippold<[email protected]>

Mock core/util/paths.js to read CONTINUE_GLOBAL_DIR dynamically instead of caching it at module load time. This fixes test isolation issues where tests running in parallel would share the same GlobalContext file path. Root cause: The CONTINUE_GLOBAL_DIR constant in core/util/paths.ts is computed via an IIFE at module load time. When tests set different temp directories in beforeEach, the module had already cached the original value. Solution: Mock getContinueGlobalPath, getIndexFolderPath, and getGlobalContextFilePath to read process.env.CONTINUE_GLOBAL_DIR on each call, allowing proper test isolation. Also adds interopDefault to vitest config for better CommonJS handling. Authored by: Aaron Lippold<[email protected]>

aaronlippold · 2025-12-26T17:42:48Z

Review Comments Addressed

Both AI review comments have been resolved:

P1 (Security) - `allowHeadless` bypassing explicit exclusions ✅

Fixed in 4062ff6

The allowMcpInHeadless check now respects explicit "exclude" permissions:

const allowMcpInHeadless =
  !tool.isBuiltIn &&
  isHeadless &&
  tool.allowHeadless &&
  result.permission !== "exclude";  // ← Added this check

P2 (Test) - Helper coercing `undefined` to `false` ✅

Fixed in 4062ff6

The test helper now preserves undefined instead of coercing to false:

// Before (bug):
allowHeadless: allowHeadless ?? false,

// After (fixed):
...(allowHeadless !== undefined && { allowHeadless }),

This ensures the test "should deny MCP tool with allowHeadless=undefined" actually tests undefined behavior, not false.

Both review threads are now outdated as the underlying code has been updated.

RomneyDa

@aaronlippold if there are issues with MCP tools in headless I think that is a bug and we should allow any MCP tools which are included. Could you clarify if this would fix the issue you're addressing here? That is, rather than adding a configuration option, just make sure any MCP tools are enabled in headless?

aaronlippold · 2026-01-06T22:41:55Z

That could be a different way to solve it. I can go through it again and see if that would fix it.

aaronlippold · 2026-01-06T22:42:00Z

That could be a different way to solve it. I can go through it again and see if that would fix it.

RomneyDa · 2026-01-13T23:53:45Z

@aaronlippold double checked this with the team and confirmed that we want MCP tools to just work out of the box in headless, so likely just a tweak to tool permissions should fix. Currently when using --agent any MCP tools in the agent will be allowed, and I think using --mcp you'd expect the same, so I think --config acting differently is probably more confusing than not, although I agree that the ultra-security conscious approach would be to default to false. I think for now, security-conscious users can pass a custom --config or use --mcps with only the tools they want.

That being said we should fix the bug where MCP tools simply aren't available in headless. I think the bug is likely here in tool permission service, where we don't actually have handling for the mcp: syntax (likely an uncaught hallucination)

// Allow MCP tools (no way to know if they're read only but shouldn't disable mcp usage in plan)
          { tool: "mcp:*", permission: "allow" },

What are your thoughts on this?

aaronlippold · 2026-01-14T01:57:50Z

Hi, my goal is resolution of the functionality so if the team has a way that they’re comfortable with resolving that it doesn’t have to be my Way. I’m happy if we think there’s a more efficient path. Happy to work with the team on that.

…

-------- Aaron Lippold ***@***.*** 260-255-4779 twitter/aim/yahoo,etc. 'aaronlippold'

On Tue, Jan 13, 2026 at 18:54 Dallin Romney ***@***.***> wrote: *RomneyDa* left a comment (continuedev/continue#9327) <#9327 (comment)> @aaronlippold <https://github.com/aaronlippold> double checked this with the team and confirmed that we want MCP tools to just work out of the box in headless, so likely just a tweak to tool permissions should fix. Currently when using --agent any MCP tools in the agent will be allowed, and I think using --mcp you'd expect the same, so I think --config acting differently is probably more confusing than not, although I agree that the ultra-security conscious approach would be to default to false. I think for now, security-conscious users can pass a custom --config or use --mcps with only the tools they want. That being said we should fix the bug where MCP tools simply aren't available in headless, with a tweak to tool permissions, likely to call out all the built ins specifically and then allow any others. What are your thoughts on this? — Reply to this email directly, view it on GitHub <#9327 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALK42HJZCWDSMULE5S3CZ34GWAR5AVCNFSM6AAAAACQCC6W46VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTONBXGA3DCMRRHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

aaronlippold requested a review from a team as a code owner December 26, 2025 15:24

aaronlippold requested review from Patrick-Erichsen and removed request for a team December 26, 2025 15:24

github-project-automation bot added this to Issues and PRs Dec 26, 2025

github-project-automation bot moved this to Todo in Issues and PRs Dec 26, 2025

dosubot bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Dec 26, 2025

cubic-dev-ai bot reviewed Dec 26, 2025

View reviewed changes

extensions/cli/src/stream/mcp-headless.test.ts Outdated Show resolved Hide resolved

extensions/cli/src/stream/handleToolCalls.ts Outdated Show resolved Hide resolved

continue bot mentioned this pull request Dec 26, 2025

docs: add allowHeadless documentation for MCP servers in CLI headless mode #9328

Closed

aaronlippold force-pushed the pr/mcp-allow-headless-option branch 2 times, most recently from f6cd721 to a054c6d Compare December 26, 2025 16:58

aaronlippold force-pushed the pr/mcp-allow-headless-option branch from a054c6d to 4db8aa8 Compare December 26, 2025 17:17

RomneyDa requested changes Jan 6, 2026

View reviewed changes

github-project-automation bot moved this from Todo to In Progress in Issues and PRs Jan 6, 2026

feat(cli): add allowHeadless option for MCP servers in headless mode #9327

Are you sure you want to change the base?

feat(cli): add allowHeadless option for MCP servers in headless mode #9327

Uh oh!

Conversation

aaronlippold commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Commit 1: Feature (4062ff6)

Commit 2: Test Isolation Fix (4db8aa8)

AI Code Review

Checklist

Screen recording or screenshot

Tests

Uh oh!

continue bot commented Dec 26, 2025

Uh oh!

continue-development-app bot commented Dec 26, 2025

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

continue bot commented Dec 26, 2025

📚 Documentation Updates Available

Changes Overview

Next Steps

Uh oh!

continue bot commented Dec 26, 2025

📚 Documentation PR Created

Uh oh!

aaronlippold commented Dec 26, 2025

Review Comments Addressed

P1 (Security) - allowHeadless bypassing explicit exclusions ✅

P2 (Test) - Helper coercing undefined to false ✅

Uh oh!

RomneyDa left a comment

Choose a reason for hiding this comment

Uh oh!

aaronlippold commented Jan 6, 2026

Uh oh!

aaronlippold commented Jan 6, 2026

Uh oh!

RomneyDa commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaronlippold commented Jan 14, 2026 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aaronlippold commented Dec 26, 2025 •

edited

Loading

Commit 1: Feature (`4062ff6`)

Commit 2: Test Isolation Fix (`4db8aa8`)

P1 (Security) - `allowHeadless` bypassing explicit exclusions ✅

P2 (Test) - Helper coercing `undefined` to `false` ✅

RomneyDa commented Jan 13, 2026 •

edited

Loading